Improve the migration guide

Add some hints about dealing with colors.

diff --git a/docs/reference/gtk/migrating-GtkStyleContext.xml b/docs/reference/gtk/migrating-GtkStyleContext.xml
index b366e65e91d38e40b7a08965d6a2c1f3f05b60a3..775fee0545a770823fb17852ebb9c96777543a51 100644 (file)
--- a/docs/reference/gtk/migrating-GtkStyleContext.xml
+++ b/docs/reference/gtk/migrating-GtkStyleContext.xml
@@ -140,6 +140,7 @@
       although custom widgets may define their own, which themes may
       attempt to handle.
     </para>
+
   </refsect2>
 
   <refsect2 id="gtk-migrating-GtkStyleContext-parser-extensions">
@@ -357,6 +358,37 @@
       independently.
     </para>
 
+    <para>
+      Access to colors has also changed a bit. With #GtkStyle, the common
+      way to access colors is:
+      <informalexample><programlisting>
+      GdkColor *color1;
+      GdkColor color2;
+
+      color1 = &amp;style->bg[GTK_STATE_PRELIGHT];
+      gtk_style_lookup_color (style, "focus_color", &amp;color2);
+      </programlisting></informalexample>
+      With #GtkStyleContext, you generally use #GdkRGBA instead of #GdkColor
+      and the code looks like this:
+      <informalexample><programlisting>
+      GdkRGBA *color1;
+      GdkRGBA  color2;
+
+      gtk_style_context_get (context, GTK_STATE_FLAG_PRELIGHT,
+                             "background-color", &amp;color1,
+                             NULL);
+      gtk_style_context_lookup_color (context, "focus_color", &amp;color2);
+
+      ...
+
+      gdk_rgba_free (color1);
+      </programlisting></informalexample>
+      Note that the memory handling here is different: gtk_style_context_get()
+      expects the address of a GdkRGBA* and returns a newly allocated struct,
+      gtk_style_context_lookup_color() expects the address of an existing
+      struct, and fills it.
+    </para>
+
     <para>
       It is worth mentioning that the new file format does not support
       custom keybindings nor stock icon mappings as the RC format did.